<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01//EN"
   "http://www.w3.org/TR/html4/strict.dtd">

<html lang="en">
<head>
	<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
	<title>PDoc</title>
	<meta name="generator" content="TextMate http://macromates.com/">
	<meta name="author" content="Tobie Langel">
	<!-- Date: 2008-02-25 -->
	<link rel="stylesheet" href="/stylesheets/reset.css" type="text/css" media="screen" charset="utf-8">
	<link rel="stylesheet" href="/stylesheets/main.css" type="text/css" media="screen" title="no title" charset="utf-8">
	
</head>
<body>
	<div id="wrapper">
		<div id="header">
			<h1><a href="/"><img src="/images/pdoc.jpg" alt="PDoc" /></a></h1>
		</div>
		<div id="navigation">
			<ul>
				<li><a href="/documentation.html">documentation</a></li>
				<li><a href="http://github.com/tobie/pdoc/tree/master">source code</a></li>
				<li><a href="http://prototype.lighthouseapp.com/projects/8889-pdoc/">bug tracker</a></li>
				<li><a href="http://groups.google.com/group/pdoc">mailing list</a></li>
			</ul>
		</div>
		<div id="content">
<h1 id="documentation">Documentation</h1>

<h2 id="comments">Comments</h2>

<p>Documentation comments start with <code>/**</code> and end with <code>**/</code>. Each new line starts with <code>*</code>. </p>

<pre><code>/** ...
 *  ...
 **/
</code></pre>

<h2 id="tags">Tags</h2>

<p>The first line of a comment is reserved for tags. Tags are separated by a comma followed by whitespace (&#8220;, &#8220;). They can be either a tag name or a key / value pair separated by a colon and a space (<code>:</code>).</p>

<p>Currently accepted tags are: <code>deprecated</code>, <code>section:</code>, <code>alias of:</code>, <code>related to:</code></p>

<pre><code>/** deprecated, section: DOM, alias of: Element#descendantOf
 *  Element#childOf(@element, className) -&gt; Element
 *  ...
 **/
</code></pre>

<h2 id="ebnf">EBNF</h2>

<p>The lines directly following tags are reserved for the EBNF description of the documented object. Typically, there&#8217;s only one EBNF per documented object. However, some objects might require more than one.</p>

<pre><code>/** 
 *  Element#down(@element[, cssSelector][, index]) -&gt; Element | null
 *  ...
 **/

/** 
 *  Element#writeAttribute(@element, attribute[, value = true]) -&gt; Element
 *  Element#writeAttribute(@element, attributes) -&gt; Element
 *  ...
 **/
</code></pre>

<h3 id="arguments">Arguments</h3>

<p>For all methods, functions, etc. parentheses around the arguments are required even if no arguments are present.
The syntax for arguments is as follows:</p>

<h4 id="required_arguments">required arguments</h4>

<pre><code>/** 
 *  Event.stop(event) -&gt; Event
 *  ...
 **/
</code></pre>

<h4 id="optional_arguments">optional arguments</h4>

<p>Optional arguments are surrounded by squared brackets (<code>[]</code>).</p>

<pre><code>/** 
 *  String#evalJSON([sanitize]) -&gt; Object | Array
 *  ...
 **/
</code></pre>

<p>A default value may be indicated using the equal sign (<code>=</code>).</p>

<pre><code>/** 
 *  String#evalJSON([sanitize = false]) -&gt; Object | Array
 *  ...
 **/
</code></pre>

<p>Note that the argument separating comas belong <em>inside</em> the brackets.</p>

<pre><code>/** 
 *  Event.findElement(event[, cssSelector]) -&gt; Element | null
 *  ...
 **/
</code></pre>

<p>Arguments can be described below the EBNF description using the following syntax:</p>

<pre><code>- argumentName (acceptedTypes...): description.
</code></pre>

<p>For example (notice the 4 space indent in the last line): </p>

<pre><code>/** 
 *  Event.findElement(event[, cssSelector]) -&gt; Element | null
 *  - event (Event): a native Event instance
 *  - cssSelector (String): a optional CSS selector which uses
 *      the same syntax found in regular CSS.
 **/
</code></pre>

<h3 id="supported_ebnf_types">Supported EBNF types</h3>

<h4 id="namespace">Namespace</h4>

<pre><code>/** 
 *  Ajax
 *  ...
 **/

/** 
 *  Prototype.Browser
 *  ...
 **/
</code></pre>

<h4 id="classes">Classes</h4>

<p>Classes require a <code>class</code> prefix:</p>

<pre><code>/** 
 *  class Ajax.Base
 *  ...
 **/
</code></pre>

<p>Sub-classes can indicate their parent just like in the Ruby syntax:</p>

<pre><code>/** 
 *  class Ajax.Request &lt; Ajax.Base
 *  ...
 **/
</code></pre>

<p>Where <code>Ajax.Base</code> is the parent class and <code>Ajax.Request</code> the subclass.</p>

<p>Included mixins are indicated like so:</p>

<pre><code>/** 
 *  class CustomHash
 *  includes Enumerable, Comparable
 **/
</code></pre>

<h4 id="mixins">Mixins</h4>

<p>Mixins are indicated by a <code>mixin</code> prefix:</p>

<pre><code>/** 
 *  mixin Enumerable
 *  ...
 **/
</code></pre>

<h4 id="constructors">Constructors</h4>

<p>Constructors require the <code>new</code> prefix and their arguments.</p>

<pre><code>/** 
 *  new Element(tagName[, attributes])
 *  ...
 **/

/** 
 *  new Foobar()
 *  ...
 **/
</code></pre>

<h4 id="klass_methods">Klass Methods</h4>

<p>Klass methods are identified by a dot (<code>.</code>).</p>

<pre><code>/** 
 *  Array.from([iterable]) -&gt; Array
 *  ...
 **/
</code></pre>

<h4 id="instance_methods">Instance Methods</h4>

<p>Instance methods are identified by the hash symbol (<code>#</code>).</p>

<pre><code>/** 
 *  Array#first() -&gt; Array element
 *  ...
 **/
</code></pre>

<h4 id="utilities">Utilities</h4>

<p>Utilities are global functions starting with a dollar-sign (<code>$</code>).</p>

<pre><code>/** 
 *  $w(string) -&gt; Array
 *  ...
 **/
</code></pre>

<h4 id="methodized_methods">Methodized Methods</h4>

<p>Methodized methods are methods which are both available as a class method and an instance method, in which case the first argument becomes the instance object itself. For example, all of <code>Element</code>&#8217;s instance methods are methodized and thus also available as class methods of <code>Element</code>. Methodized methods are indicated by prefixing their first argument with the <code>@</code> symbol.</p>

<pre><code>/** 
 *  Element#hide(@element) -&gt; Element
 *  ...
 **/
</code></pre>

<h4 id="klass_properties">Klass Properties</h4>

<p>Klass properties are identified by a dot (<code>.</code>).</p>

<pre><code>/** 
 *  Ajax.Responders.responders -&gt; Array
 *  ...
 **/
</code></pre>

<h4 id="instance_properties">Instance Properties</h4>

<p>Instance properties are identified by the hash symbol (<code>#</code>).</p>

<pre><code>/** 
 *  Ajax.Response#responseText -&gt; String
 *  ...
 **/
</code></pre>

<h4 id="constants">Constants</h4>

<p>Constant must have their value specified using the equal sign (<code>=</code>).</p>

<pre><code>/** 
 *  Prototype.JSONFilter = /^\/\*-secure-([\s\S]*)\*\/\s*$/
 *  ...
 **/
</code></pre>

<h3 id="events">Events</h3>

<p>Some methods can fire native or custom events. These are indicated below the arguments descriptions:</p>

<pre><code>/** 
 *  Ajax.Request#respondToReadyState(readyState) -&gt; undefined
 *  - readyState (Number): a number from 0 to 4 corresponding to the state of the request.
 *  fires ajax:created, ajax:completed
 **/
</code></pre>

		</div>
		<div id="sidebar">
		
		</div>
		<div id="footer">
			<p>&copy; 2008 Tobie Langel. PDoc logo &copy; 2008 Sam Stephenson.</p>
		</div>
	</div>
</body>
</html>
